# Return

The `return` node is the building block of everything in Nodysseus. They are the square nodes. It is roughly equivalent to a function in most programming languages. Its purpose is to receive inputs and return an output. Like a normal function, its inputs are named arguments, and its output is the value along the `value` edge. It has some additional features that a normal function does not have. It can output a `display` which is used to populate the info popup of the return and nodes referencing the return's graph. `publish` and `subscribe` are used for sending and handling events between different `return` and `event_subscriber` nodes across the application. `lib` is a utility for broadcasting libraries to all connected nodes and sub-nodes.

Graphs are required to have a `return` node as the last node in the graph, but `return` can also be used elsewhere for publishing and subscribing to events, or for using a node's output as input for multiple nodes.


## Basic input edges

### `value` edge (output)

The `value` input to a `return` node is the value that will be passed along the output edge of the return. When it is the last node in a graph, any nodes referencing that graph will also pass on the `value` along their output edge if they are not being evaluated for their `display`.

### `args` edge (inputs)

In the graph above any `return` node there are triangular nodes labeled `arg` with a node value. These `arg` nodes, or inputs to the graph, are like named parameters for a function - they can have any value stored in them, and can be placed anywhere in the graph to access a graph's arguments. The `arg` node's value corresponds to the named argument to access.

A `return` node's arguments are set in a few different ways, but the primary one is using the `args` input edge. The object passed along the `args` node becomes the named arguments, where the name is the object's key, and the value is the object's value at the specified key. In practical terms, this means that when the input `args` node has no value or ref, any edge becomes an argument with the same name as the edge.

### `display` edge

When the `return` node is the output node of a graph, the `display` input is shown in the bottom right. Any nodes referencing the graph will show the `display` output in the node info popup. Elsewhere in the graph, the `display` output shows in the node info of the `return` node. The display can also be split into `background` and `resultPanel` inputs which will display appropriately. The `background` input is only displayed when the graph is the current graph - it will not show in the info window.

## Advanced input edges

### `metadata` edge

The `metadata` edge should contain an object with metadata about the graph. The valid object fields are `values`, and `parameters`. 

By default, without `parameters`, the UI will find all `arg` nodes and show their values in the node info window as named arguments. `parameters` is a helper input to indicate to the UI which named inputs are expected and will take precedence over parsing the `arg` nodes. 

All the items in `values` will be available as autocomplete when using the graph.

### `subscribe` edge

The `subscribe` edge subscribes to app-wide events. It should be an object with the event names as keys, and runnables as values. When the event is fired, the corresponding runnable is run.

### `lib` edge

Any globally used libraries and utilities can be passed to all nodes evaluated by this `return`. This should primarily be used for libraries that need to be passed many levels deep.

## Usage cases

### Multiple outputs

A node can only have one output.

However, in the same way that a function's arguments can be used multiple times in the function, an argument to a return node can be used in any of the ancestors of that node. Any time a node's output needs to go to multiple nodes, connect it to the `args` edge, and then on the `value`, `publish`, or `subscribe` edges reference that `arg`.

Having a single output is also a "functional programing" paradigm - a function has one output and multiple inputs.

This restriction is in place because with multiple outputs, a node graph can get very messy. In graph theory terms it goes from a tree (specifically an in-tree) to a more generic directed acyclic graph. There are many directed acyclic graphs which cannot be drawn without edges crossing, and even figuring out the fewest number of crossings is a very difficult problem. In contrast, a tree is very easy to draw, even though Nodysseus gets it wrong sometimes because it's trying to optimize for space.